home *** CD-ROM | disk | FTP | other *** search
/ The Atari Compendium / The Atari Compendium (Toad Computers) (1994).iso / files / umich / sound / players / digistuf.arc / DIGIVEC / DIGIVEC.DOC next >
Text File  |  1992-08-20  |  9KB  |  232 lines
  1.          
  2.          
  3.                  Digivec
  4.       
  5.                         Copyright (C) 1991, 1992
  6.                 By David Baggett
  7.  
  8.  
  9. --------------------------------------------------------------------------------
  10.                   User Contract
  11.  
  12. This program is FREE.  You may distribute it at will, provided you
  13.     
  14.     1) do not charge any money for it,
  15.     2) distribute it WITH the documentation, and
  16.     3) do not change the program or documentation in ANY WAY.
  17.  
  18. --------------------------------------------------------------------------------
  19.  
  20.  
  21. Introduction  
  22. ------------
  23.  
  24.       "My ST was so boring before I got Digivec!"
  25.  
  26.       "Programming just isn't the same without it."
  27.  
  28.       "I just wouldn't know what to do if someone took away my Digivec!"
  29.  
  30.  
  31.    You'll agree with these happy customers once you too try the exciting new
  32. shareware utility that's taking the ST world by storm!  It's Digivec, and
  33. once you install it on your system, you won't know how you ever lived
  34. without it.
  35.  
  36.    Got your attention?  Good.  Okay, listen up.  Digivec lets you install
  37. digitized sounds to be played when various system events occur.  Like
  38. bus errors.  Illegal instruction traps.  Or line A calls.  Even...
  39. <gasp!> GEM critical errors.
  40.  
  41.  
  42. General Usage
  43. -------------
  44.  
  45.    Put digivec.prg in your AUTO folder.  Then create a file called 
  46. digivec.inf with a standard ASCII text editor and put it in the root 
  47. directory of your boot partition (e.g., if your AUTO folder is C:\AUTO\, 
  48. put digivec.inf in C:\).
  49.  
  50.    In digivec.inf you specify which sounds will be installed, and what events
  51. will trigger them.  Each entry starts with a sample file name, enclosed
  52. in square brackets, followed by the sample playback speed, in Hertz, 
  53. followed by a list of system vectors which will trigger the sound.  Here's 
  54. an example digivec.inf file:
  55.  
  56. [d:\usr\sounds\buserror.snd]    11000    $8 $C
  57.  
  58. This file tells Digivec to load the sample named d:\usr\sounds\buserror.snd
  59. and to play it at 11000 Hz whenever vectors 8 (hex) and C (hex) are jumped 
  60. through (in this case, any time either a bus error or address error occur).
  61.  
  62.    Increasing the number 11000 will make the sound play faster; decreasing
  63. it will make the sound play slower.
  64.  
  65.    The digivec.inf file can contain as many of these entries as you want;
  66. the only limitation is that all the samples have to fit in memory at once.
  67.  
  68.    Note that file names MUST be enclosed in square brackets.
  69.  
  70.  
  71. Specifying an Alternate D/A Device
  72. ----------------------------------
  73.  
  74.    Digivec can be configured to play its samples through other D/A devices.
  75. Currently, the Hippo/Navarone and ST Replay digitizers are supported.  The
  76. STe's (and TT's, and Falcon's) 8-bit D/A is also supported, with either the
  77. DMA or the MFP for timing.  (If you use the DMA for timing, you can only play
  78. at certain sample rates, so sounds may sound too fast or slow.  On the other
  79. hand, if you use the MFP for timing you can play stereo samples at any rate
  80. but the sound quality isn't quite as good.)
  81.  
  82. Other digitizers will be supported if people send me info on them.
  83.  
  84.    To use an alternate D/A device, put one of the following keywords 
  85. in curly brackets somewhere in your digivec.inf file:
  86.  
  87.     hippo    replay    dma    mfp
  88.  
  89. For example, a digivec.inf containing
  90.  
  91. {dma}
  92. [d:\usr\sounds\buserror.snd]    11000    $8
  93. [d:\usr\sounds\youlose.snd]    11000    $C
  94.  
  95. will cause Digivec to play the all sounds through the DMA sound device, using
  96. the DMA for timing.  (This won't work on machines that don't have DMA sound
  97. capabilities, of course.)
  98.  
  99.    Note that the normal ST keyclick will still be masked, even if
  100. you don't use the speaker as the D/A device.  
  101.  
  102.  
  103. Different Kinds of Samples
  104. --------------------------
  105.  
  106.    Unless you tell it otherwise, Digivec assumes your sounds are unsigned
  107. 8-bit mono samples.  You can use stereo and/or unsigned samples with Digivec
  108. too, by putting one of the following keywords in brackets after the filename:
  109.  
  110.     stereo    signed
  111.  
  112. For example, a digivec.inf containing
  113.  
  114. [d:\usr\sounds\lossage.snd]    {stereo}    11000    $C
  115.  
  116. will make Digivec interpret lossage.snd as stero data instead of mono. 
  117. (Stereo sounds will play on mono devices; the channels are just mixed
  118. together.)
  119.  
  120. Similarly the line
  121.  
  122. [d:\usr\sounds\lossage.snd]    {signed}    11000    $C
  123.  
  124. tells Digivec that lossage.snd has signed 8-bit samples instead
  125. of unsigned samples.  Some digitizing software saves sounds in this
  126. format instead of the usual unsigned format.  If you're not sure what
  127. you've got, a general rule of thumb is that if a sound sounds very noisy
  128. you should try it as signed.
  129.  
  130.  
  131. The Vectors
  132. -----------
  133.  
  134.    You can specify the system vectors either in hexadecimal (with leading $)
  135. or decimal (no leading $).  Interesting vectors for triggering sounds
  136. include (but are not limited to):
  137.  
  138.     Hex    Decimal        Description
  139.     ---    -------        -----------
  140.     $8     8        Bus Error
  141.     $C     12        Address Error
  142.     $10     16        Illegal Instruction
  143.     $14     20        Division by Zero
  144.     $20     32        Privilege Violation
  145.     $28     40        Line A Emulator
  146.     $2C     44        Line F Emulator
  147.  
  148.     $404     1028        Critical Error 
  149.     $408     1032        Process Termination
  150.     $476     1142        Drive read/write
  151.  
  152.    The first 5 vectors deal with failures caused (typically) by software
  153. bugs.  These are the things that cause the ST to put bombs on the 
  154. screen.  But it's so much more fun to have the ST say "Just what do
  155. you think you're doing, Dave?" when a bus error occurs.  (Especially
  156. if your name is Dave and you crash the machine a lot...)
  157.  
  158.    The Line A and Line F emulators are typically used to call system 
  159. functions. (Line A is used for drawing functions; Line F is used in a very 
  160. few programs for pulling off bizarre hacks and/or for floating point).  
  161. Triggering sounds with these is not terribly useful unless you're a 
  162. programmer-type and want to see just what a given application is up to.  
  163. (It's also neat to install a sound at Line A and then run NEOchrome.)
  164.  
  165.    GEM uses the critcal error vector when various things confuse it.  The 
  166. most common of these is trying to read or write with no disk in the drive.
  167.  
  168.    The process termination vector will trigger a sound whenever any program
  169. exits.  This can get extremely annoying after a while.  Trust me.  It's
  170. really fun to install this one on a machine when the owner isn't looking.
  171.  
  172.    If you miss your Atari 800, with it's "boop boop boop" disk access,
  173. you can trigger a sound with the disk read/write vector.  Another good
  174. one to surprise your friends with.
  175.  
  176.  
  177. Command Line Usage
  178. ------------------
  179.  
  180.    In previous versions of Digivec, invoking the program from the 
  181. desktop or command line was tricky.  Those problems have been fixed.
  182. To call Digivec from the desktop, rename it digivec.ttp and double
  183. click on it.  To run it from a command shell, type
  184.  
  185.     digivec
  186.    
  187. and press return.
  188.    
  189.    Note that when you run Digivec from the desktop or a command shell,
  190. it looks for digivec.inf in the current working directory.
  191.  
  192.  
  193. Technical Information
  194. ---------------------
  195.  
  196.    Digivec works by installing a new exception handler for each vector
  197. specified in digivec.inf.  Each new handler just plays the appropriate
  198. sound then jumps through the old vector.  This should not adversely affect 
  199. the system in any way, except in cases where timing is critical.  (So 
  200. don't trigger sounds with the horizontal blank interrupt!)
  201.  
  202.    Minor problems are caused by the fact that when GEM loads (after AUTO
  203. folder programs are finished), it obliterates the critical error vector and 
  204. the process termination vector and installs its own.  To get around this,
  205. Digivec waits for GEM to finish loading before it actually installs any 
  206. vectors.  The method Digivec uses to see if GEM has finished loading
  207. is a bit, ah, undocumented (I think), so I'd be interested to know if
  208. it doesn't work on certain versions of TOS.  (How's that for confidence?)
  209.  
  210.  
  211. Caveats
  212. -------
  213.  
  214.    Digivec will replace any vector in the system.  It does not check to make 
  215. sure the vectors you specify are reasonable.  This means that you could 
  216. theoretically replace some vector in the system that no one else has thought 
  217. of replacing, w